

                        Application Statistics
                        ======================
                        

Documentation for !APPstat application version 1.30 11-Apr-2020
for RISC OS 3.1 and later.

Issue: 1.30 11-Apr-2020, replaces:      0.10 03-May-1995
                                        0.90 28-May-1995
                                        0.99 17-Jun-1995
                                        1.10 07-Jun-1998
                                        1.21 07-Jun-1998
                                        1.22 15-Nov-2001
                                        1.23 23-Jun-2013 
Author: David J Ruck

Copyright  DEEJ Technology PLC 1995-2020



Overview
========

The !APPstat application provides information on the activity of all running 
RISC OS application in your machine, it is the best tool available for
ensuring  that your WIMP programs are fast and efficient.

It is intended for programmers who wish to debug or improve the efficiency
of  their applications. It does this by showing exactly which WIMP events
are  being delivered to each application, in what quantity, and how long the 
application takes to process them.

It can also be used by the merely incurably curious for a fascinating
insight  into  what the computer is getting up to, and which tasks are
hogging the CPU.



Using !APPstat
==============

When started !APPstat installs its own icon on the icon bar, clicking on it
will  display the main window. This window contains information on all 
applications that are active at the current time.

Each running application has its own entry, giving its name, a value and a 
graphic display of this value, similar to the bars used in the Task
manager's  window.

The value is one of four types, the number of calls to the application or
the  time spent in the application, either as a total value or the value
occurring over  a definable time interval. Switching between these displays
is described in the  !APPstat menu section below.

The Main Window The first entry in the window is the total value of all the 
                entries below corresponding to the time between updates of
                the display. The next two bars display the system overhead 
                and the totals for all applications.
                
                The system overhead is the time the WIMP spends in the 
                WIMP_Poll SWI. When displaying call counts all three bars 
                have the same value, corresponding to the number of calls 
                made to all applications.

                The bars below correspond to the call/times for each running 
                application. Clicking on All Applications any of the 
                application names will display a subwindow for that 
                application. The All Applications subwindow shows the 
                combined information for every running application.

                Any new applications which are started while !APPstat is run 
                are added to the end of the main window.
                
Sub Windows     The subwindows for each application are similar to that of 
                the main window, except that the number of calls or timings 
                for each WIMP event and message that the application receives
                are displayed.

                The first entry is the total for that application, as is 
                displayed in the main window. The next twenty entries 
                correspond to each of the event codes returned by the 
                Wimp_Poll SWI. The remaining entries in the window are 
                the calls/timings for each type of message delivered to 
                the application on event types 17 and 18 (Send Message and 
                Send Message Want Ack). Messages returned by event 19 
                (Acknowledge Message) are not counted by these bars.
                
                Events and messages, which are recognised by the program 
                are assigned names, others will be displayed as a numbers. 
                Most common message types are already displayed, others will 
                be added to the window when they occur.

Counter Windows Clicking on the Applications & System, or System Overhead 
                entries in the main window or any entry in a subwindow will 
                call up a counter window.
                
                The counter window shows the number of calls or the time 
                spent processing (an individual event/message or the total 
                for an application) occurring in the set interval, as a 
                vertical line. The display scrolls to the left each interval 
                to show a new value, thus the variation in activity of a 
                application can be monitored over a period of time.

                It is easier to see sudden peaks of activity in a counter 
                window than in the main and subwindows, which do not need 
                to be open once a counter window has been called up. Any 
                number of counter windows (memory permitting) can be active 
                at once.
                
                The counter window display automatically scales up and down 
                to fit the maximum value in the window. At the default scale 
                4 OS units (1 rectangular pixel) is equivalent to one call or
                1s, each subsequent scale is half the last shown by the 
                horizontal grey lines. These do not represent values but show 
                how many times the height of the bars have been halved;
                e.g. 1 line =  scale, 2 lines =  scale, 10 lines 1/1024th 
                scale.


Window menu
-----------
The main window and all subwindows provide a menu, the entries are described
below.

Totals          This affects the main window and all subwindows. When ticked 
                the display of each window gives the number of calls or time 
                spent processing for each application or WIMP event since 
                !APPstat was started (or Zero counts was used). 

Per interval    This also affects the main window and all subwindows; it 
                changes the displays to show the number of calls / time spent
                over a given time interval, set by Update rate below. The 
                dark grey window titles changes to show the desired rate, and
                in brackets, the actual rate achieved in milliseconds.
                
Call Counts     This option effects the main window, all subwindows and all 
                counters currently displayed. When ticked the number of calls
                to each application or for each WIMP event/message will be 
                displayed in the windows.
                
Timings         When ticked all windows and counters will display the time 
                the applications spend processing each WIMP event/message. 
                The timings are displayed in seconds, with the factional 
                value accurate to the nearest microsecond.
                
Update rate     The value entered into the writable sub menu determines the 
                interval used when displaying in Per interval mode, and the 
                update rate of counter windows, which always show the number 
                of calls/timings during this interval in both Totals and Per 
                interval modes.
                
                The value entered is in milliseconds (1/1000th sec), due to 
                RISC OS limitations it is only possible to set the rate to 
                the nearest 10ms, a minimum of 100ms is imposed. When using 
                large values it should be noted that the new value only comes
                into effect on the next scheduled update.

                If a lot of tasks are running or a number of subwindows or 
                counter windows are open it may not be possible for the 
                program to update its displays at very high rates, this is 
                automatically taken into account, and the values and sizes 
                of bars are corrected accordingly.

Scale           Bars in the main and subwindows are automatically scaled to 
                fit the largest in the window by default, this can however, 
                lead to the bars for small values disappearing. Clicking on 
                the Scale option on the main menu toggles automatic and 
                manual scaling, which is shown by a tick next to scale.

                When using manual scaling values can be entered in the 
                writable submenu, integer and fractional values are allowed.


Iconbar menu
------------
Info            Displays program information and version number.

Display         Displays the main window, equivalent to clicking on the 
                !APPstat icon.

Kill            Quits the application and kills the APPmod module which 
                performs the counting and timing monitoring of applications. 
                This ensures the small processing overhead imposed by the 
                module is removed.

Quit            Quits the application, the APPmod module is not killed so if 
                the program is run again, the application counts and timing 
                totals will still have been incremented while the program 
                was not running, see Technical details below.



Technical details
=================

!APPstat works by loading a special module APPmod which installs WIMP  pre
and postfilters to enable the module to recognise when an application has 
been switched in by the WIMP.

The postfilter enables the type of event that is being delivered to the 
application to be extracted and separate counts and timings held for each.

The timings are obtained by reading the IOC timer 0 and the monotonic 
system clock (which is incremented by the timer 0 events). The timer and 
clock values are combined to produce a second and microsecond time value.
The details below are provided for users who may wish to use this module in 
their own programs.

AppStat_stat            !APPstat uses this call every update interval to
&55900                  read the current APP call counts and timing
                        information, and calculate the correct values for 
                        the program displays.
                                
                        A call to AppStat_stat (no parameters required) returns 
                        a pointer in R0 to a memory structure (type: main_str)
                        which is described in C as:

    typedef struct
    {
        struct AppStat__str  *chain_ptr;/* pointer to chain of AppStat_str */
        timeval          sys_time;      /* total of system execution time  */
    } main_str;
    
    typedef struct AppStat__str
    {
        struct AppStat__str  *next_ptr; /* pointer to next in chain        */
        wimp_t           task;          /* task handle of application      */
        stat_str         AppStat_total; /* total count/time for this app   */
        stat_str         events[20];    /* counts/time for wimp events     */
        msgstat_str      messages[256]; /* counts/time for 256 messages    */
    } AppStat_str;

    typedef struct
    {
        wimp_msgaction   action;        /* message action or -1 not used   */
        stat_str         info;          /* count/time for message type     */
        } msgstat_str;

    typedef struct
    {
        long             count;         /* numbers of calls for item       */
        timeval          time;          /* total run time for item         */
    } stat_str;

    typedef struct
    {
        long             tv_sec;        /* time in seconds                 */
        long             tv_usec;       /* microsecond excess              */
    } timeval;


                        The main_str chain_ptr points to a list of AppStat_str
                        for each application, terminated by a 0 in next_ptr 
                        of the last AppStat_str. The first AppStat_str in the list 
                        has a task handle of -1 and corresponds to All 
                        Applications combined totals.
                        
                        Only some of the 256 possible messages entries are 
                        assigned to valid message action types initially. 
                        The msgstat_str action field contains -1 if the entry
                        is not assigned. Further entries are assigned on 
                        receipt of new message types. 

AppStat_Zero            Calling this routine causes all the counts and 
&55901                  timings to be zeroed. Counting continues immediately.

AppStat_Control         This call is used to activate (R0 = 1) or suspend 
&55902                  (R0 = 0) the modules counting and timing activity. 
                        While suspended the WIMP filters are still enabled, 
                        but computational overhead of the counting and timing
                        operations are removed.


Changes
=======

1.10    Known message list updated.
        Unknown message numbers named after module SWI chunks if appropriate.
        
1.20    Percentage display option added        

1.21    Official SWI chunk allocated.

1.22    Fix for tasks with names longer than 23 characters not updating
        correctly
        
1.23    Updated version of APPstat module, correcting abort on Raspberry Pi
        and improving accuracy on other systems when counter period has
        been reduced by the NetTime module
        
1.30    Values displayed with desktop rather than system font
        APPstat module fix for HAL calls corrupting registers on Mini.m


!SWIstat
========

Also from DEEJ Technology PLC is the companion application !SWIstat.  Using
the same style of displays !SWIstat provides information on the activity  of
all SoftWare Interrupts (SWI's) occurring in your machine, the next best 
thing to Acorns own hardware debugging systems.

It is intended for programmers who wish to debug or improve the efficiency
of  their application's or module's interface with the OS. It does this by
showing  exactly which software interrupt calls are being made, when and in
what  quantity.

!SWIstat can monitor SWI activity from all applications running in the 
machine, or just a chosen one, enabling scrutiny of a particular application 
under test. All tasks except !SWIstat can be monitored to partially remove
the  effect of running the application in a development environment.



End of APPstat User Guide.
